home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Amiga Games: Greatest Hits 1996
/
Amiga Games: Greatest Hits 1996.iso
/
userbox
/
publicdomain
/
superplay-lib_dev
/
programmers
/
docs
/
spobject_ref_eng.doc
next >
Wrap
Text File
|
1996-05-27
|
20KB
|
852 lines
$VER: SPObject_Ref_ENG.doc V2.4 (21.10.95)
© 1994-95 by Andreas R. Kleinert. All rights reserved.
- Feel free to translate this Doc-File into other languages. -
Andreas R. Kleinert,
Sandstrasse 1,
D-57072 Siegen,
Germany.
EMail: Fido Andreas Kleinert 2:2457/435.10
Usenet/InterNet Andreas_Kleinert@superview.ftn.sub.org
If nothing else works, try one of these Fido-InterNet gateways:
Andreas_Kleinert@p10.f435.n2457.z2.fido.sub.org (in Germany)
Andreas_Kleinert@p10.f435.n2457.z2.fidonet.org (USA or other)
* DO _NEVER_ ACCESS ANY SPOBJECTS DIRECTLY.
* DO NEVER BYPASS superplay.library !
THE FOLLOWING NOTES ARE ONLY FOR PROGRAMMERS OF SPOBJECTS :
Here is a listing of the function set, which any of the version 1
and version 2 SPObjects does contain, in an Autodoc-like style of
description :
SPO_AllocHandle ; since Version 1
SPO_FreeHandle
SPO_Read
SPO_StartReplay
SPO_Write
SPO_StopReplay
SPO_FreeResources
SPO_SetAccessMode
SPO_SetWriteSubType
SPO_SetWriteName
SPO_SetReadeName
SPO_FileInfoRequest
SVO_CheckFileType
SPO_SetReqIOWindow
SPO_ContinueReplay
SPO_FastForward
SPO_FastBackward
SPO_GetSampleBuffer *** OBSOLETE : Use SPO_GetSampleList()
SPO_GetSampleInfo *** OBSOLETE : Use SPO_GetSampleList()
SPO_GetSampleList ; since Version 2
SPO_SetSampleList
-----------------------------------------------------------------------------
Functions available since Version 1 :
-----------------------------------------------------------------------------
NAME
SPO_AllocHandle
SYNOPSIS
APTR SPO_AllocHandle(APTR future)
D0 -$1e A1
FUNCTION
Allocates a handle for accessing a Sample/Module via SPObjects.
INPUT(S)
future - always NULL yet
RESULT
A pointer to a new allocated Handle or NULL, if allocation failed.
WARNING
Test, if the result was NULL, or not !
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPO_FreeResources, SPO_FreeHandle
-----------------------------------------------------------------------------
NAME
SPO_FreeHandle
SYNOPSIS
VOID SPO_FreeHandle(APTR handle)
D0 -$24 A1
FUNCTION
Stops playing, frees all Resources and delocates a Handle, which has
been allocated with SPO_AllocHandle before.
INPUT(S)
handle - a valid handle
RESULT
-
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPO_AllocHandle, SPO_StopReplay, SPO_FreeResources
-----------------------------------------------------------------------------
NAME
SPO_Read
SYNOPSIS
ULONG SPO_Read(APTR handle)
D0 -$2a A1
FUNCTION
Loads the Sample/Module described by FileName, which then may
e.g. be replayed by SPO_StartReplay.
INPUT(S)
handle - a valid handle
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPO_AllocHandle, SPO_StopReplay, SPO_StartReplay, SPO_ContinueReplay,
SPO_FastForward, SPO_FastBackward, SPO_FreeHandle
-----------------------------------------------------------------------------
NAME
SPO_StartReplay
SYNOPSIS
ULONG SPO_StartReplay(APTR handle)
D0 -$30 A1
FUNCTION
Play the Sample/Module described by FileName, which has been loaded
via SPO_Read before.
Playing can be stopped either via full delocation of the handle
or temporal interruption with SPO_StopReplay.
INPUT(S)
handle - a valid handle
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPO_AllocHandle, SPO_Read, SPO_StopReplay, SPO_ContinueReplay,
SPO_FastForward, SPO_FastBackward, SPO_FreeHandle
-----------------------------------------------------------------------------
NAME
SPO_Write
SYNOPSIS
ULONG SPO_Write(APTR handle, struct SPObjectBase *SourceBase,
D0 -$36 A1 A2
APTR source_handle)
A3
FUNCTION
This functions allows to access an other SPObject, get the Sample-
Data from there (only works with SampleType-SPObjects) and
then writes this data in its own FileFormat.
*** NEW FEATURE : ***
This functions acts different in Versions >= 2 :
1) If "SourceBase" and "source_handle" are both NULL,
it is checked, whether a SampleList has been set via
"SPO_SetSampleList()", and then this SampleList is completely
saved.
ELSE
2) a) If a Version 1 SPObject is the Source, the old behaviour
takes place.
b) If a Version 2 SPObject takes place, the new SampleList
functions are supported (and completely saved).
So, what's new ? Well, if you've any self-created SampleLists,
you now can save them by just setting them via SPO_SetSampleList()
and then calling SPO_Write() with NULL parameters for the
Source-SPObject variables.
INPUT(S)
handle - a valid handle
(used for Write Access)
SourceBase - pointer to Base of other SPObject
(may be NULL for V2+ SPObjects)
source_handle - handle for accessing the other SPObject
(may be NULL for V2+ SPObjects)
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPO_AllocHandle, SPO_Read, SPO_FreeHandle
-----------------------------------------------------------------------------
NAME
SPO_StopReplay
SYNOPSIS
VOID SPO_StopReplay(APTR handle)
D0 -$3c A1
FUNCTION
Stops playing the Sample/Module, indentified by the handle.
Some SPObjects support to continue the Sample/Module with
SPO_ContinueReplay after calling SPO_StopReplay.
INPUT(S)
handle - a valid handle
RESULT
-
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPO_ContinueReplay, SPO_FreeResources, SPO_FreeHandle
-----------------------------------------------------------------------------
NAME
SPO_FreeResources
SYNOPSIS
VOID SPO_FreeResources(APTR handle)
D0 -$42 A1
FUNCTION
Frees all resources belonging to the specific Sample/Module,
indentified by the handle, which are not needed to just replay it.
Playing of the Sample/Module is not stopped and/or interrupted.
INPUT(S)
handle - a valid handle
RESULT
-
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPO_AllocHandle, SPO_StopReplay, SPO_FreeHandle
-----------------------------------------------------------------------------
NAME
SPO_SetAccessMode
SYNOPSIS
ULONG SPO_SetAccessMode(APTR handle, ULONG mode)
D0 -$48 A1 D1
FUNCTION
Initializes a Handle for ClipBoard or AmigaDOS access,
depending on the "mode" parameter.
INPUT(S)
handle - a valid handle
mode - access mode value
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
-
-----------------------------------------------------------------------------
NAME
SPO_SetWriteSubType
SYNOPSIS
ULONG SPO_SetWriteSubType(APTR handle, ULONG write_type, APTR future)
D0 -$4e A1 A2 A3
FUNCTION
Sets the write_type for a SPO_Write() call.
See description there and example SourceCodes for more and
detailed information.
INPUT(S)
handle - a valid handle
write_type - a valid temporary write_type code form the SPObject List
future - always NULL yet
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPO_Write
-----------------------------------------------------------------------------
NAME
SPO_SetWriteName
SYNOPSIS
ULONG SPO_SetWriteName(APTR handle, ULONG write_name, APTR future)
D0 -$54 A1 A2 A3
FUNCTION
Sets the write_name for a SPO_Write() call.
See description there and example SourceCodes for more and
detailed information.
INPUT(S)
handle - a valid handle
write_name - a valid AmigaDOS FilePath and -Name description
future - always NULL yet
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPO_Write
-----------------------------------------------------------------------------
NAME
SPO_SetReadName
SYNOPSIS
ULONG SPO_SetReadName(APTR handle, ULONG reade_name, APTR future)
D0 -$5a A1 A2 A3
FUNCTION
Sets the reade_name for a SPO_Read() call.
See description there and example SourceCodes for more and
detailed information.
INPUT(S)
handle - a valid handle
write_name - a valid AmigaDOS FilePath and -Name description
future - always NULL yet
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPO_Write
-----------------------------------------------------------------------------
NAME
SPO_FileInfoRequest
SYNOPSIS
ULONG SPO_FileInfoRequest(APTR handle, struct Window *window,
D0 -$60 A1 A2
APTR future)
A3
FUNCTION
Pops up an Info-Requester with more or less detailed information
on the currently loaded Sample/Module.
A window pointer may be given to select the place to pop it up.
INPUT(S)
handle - a valid handle
window - a valid Window Pointer or NULL
future - always NULL yet
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPO_SetReqIOWindow
-----------------------------------------------------------------------------
NAME
SPO_CheckFileType
SYNOPSIS
ULONG SPO_CheckFileType(BPTR filehandle, UBYTE *filename,
D0 -$66 A1 A2
struct SPOCheckFile *spo_check)
A3
FUNCTION
Checks, if the given file (or ClipBoard entry, or whatever)
fits to this SPObject and can be handled therein.
Upto Version 2 of superplay.library ClipBoard-Support with
external SPObjects would not have worked at all.
Since V2 the specification of external Version 2 SPObjects
has been modified to allow ClipBoard and other media usage :
To preserve compatibility, this has been done by using the
"future" parameter as a pointer to a structure (defined in
"include:spobjects/spobjects.h"), which contains media
information.
This pointer may be NULL, so that you have to assume default
settings, if there's not such a structure.
For disk-access, this pointer will not be set at all, anyway.
Also be prepared, to handle NULL pointers to filename :
if ClipBoard usage is forced, there will no filename be needed.
If you don't support any filename-less medias, just do a silent
exit.
Currently - for compatibility reasons - superplay.library will
supply a dummy filename and a dummy file for those SPObjects,
which may not handle a NULL pointer correctly.
So handle SPOCheckFile structures with a HIGHER priority, because
currently there's always a dummy-file (mostly empty) available.
INPUT(S)
handle - a valid handle
name - a valid AmigaDOS FileName
spo_check - a pointer to a SPOCheckFile structure or NULL
for disk-access (default)
RESULT
NULL or an adequate SVERR-Errorcode.
SINCE
... Version 1 SPObjects.
SEE ALSO
-
-----------------------------------------------------------------------------
NAME
SPO_SetReqIOWindow
SYNOPSIS
ULONG SPO_SetReqIOWindow(APTR handle, struct Window *window)
D0 -$6c A1 A2
FUNCTION
Sets a new Default-Window (default : IntuitionBase->FirstWindow)
for any Requester IO.
INPUT(S)
handle - a valid handle
window - a valid Window Pointer or NULL
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPO_FileInfoReq
-----------------------------------------------------------------------------
NAME
SPO_ContinueReplay
SYNOPSIS
ULONG SPO_ContinueReplay(APTR handle)
D0 -$72 A1
FUNCTION
Some SPObjects support to continue a Sample/Module which
has been stopped by calling SPO_StopReplay.
INPUT(S)
handle - a valid handle
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPO_SuperPlay, SPO_StopReplay
-----------------------------------------------------------------------------
NAME
SPO_FastForward
SYNOPSIS
ULONG SPO_FastForward(APTR handle)
D0 -$78 A1
FUNCTION
Some SPObjects might support a "cassette recorder"-like way
to browse trough a Sample/Module via FastForward and Rewind.
INPUT(S)
handle - a valid handle
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPO_FastBackward
-----------------------------------------------------------------------------
NAME
SPO_FastBackward
SYNOPSIS
ULONG SPO_FastBackward(APTR handle)
D0 -$7e A1
FUNCTION
Some SPObjects might support a "cassette recorder"-like way
to browse trough a Sample/Module via FastForward and Rewind.
INPUT(S)
handle - a valid handle
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPO_FastForward
-----------------------------------------------------------------------------
NAME
SPO_GetSampleBuffer *** OBSOLETE : Use SPO_GetSampleList()
SYNOPSIS
ULONG SPO_GetSampleBuffer(APTR handle, UBYTE **buffer,
D0 -$84 A1 A2
ULONG *buffersize)
A3
FUNCTION
With Version 1 SPObjects, this is the only possibility to get
a pointer to SampleBuffers.
This function only works with SampleType-SPObjects and is used
always, when Samples are converted from from FileFormat into
an other.
This function should not be used for any other purposes, since it
is OBSOLETE since Version 2 of the SPObject specification.
There's no direct pass-through from this function to superplay.library,
but it would not suffice, anyway, since some FileFormats may
contain MORE THAN ONE Sample.
Use SPO_GetSampleList instead, which can handle more than one
Sample and also returns the information related to them.
INPUT(S)
handle - a valid handle
buffer - a pointer to a buffer pointer
buffersize - a pointer to a buffersize pointer
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPO_GetSampleList
-----------------------------------------------------------------------------
NAME
SPO_GetSampleInfo *** OBSOLETE : Use SPO_GetSampleList()
SYNOPSIS
ULONG SPO_GetSampleBuffer(APTR handle, ULONG *samplesPerSec,
D0 -$8a A1 A2
ULONG *volume, APTR future)
A3 D1
FUNCTION
With Version 1 SPObjects, this is the only possibility to get
a pointer to Sample information.
This function only works with SampleType-SPObjects and is used
always, when Samples are converted from from FileFormat into
an other.
This function should not be used for any other purposes, since it
is OBSOLETE since Version 2 of the SPObject specification.
There's no direct pass-through from this function to superplay.library,
but it would not suffice, anyway, since some FileFormats may
contain MORE THAN ONE Sample.
Use SPO_GetSampleList instead, which can handle more than one
Sample and also returns the information related to them.
This function only returns info on 8 Bit Samples.
INPUT(S)
handle - a valid handle
samplesPerSec - a pointer to a buffer pointer
volume - a pointer to a buffersize pointer
future - always NULL yet
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPO_GetSampleList
-----------------------------------------------------------------------------
Functions added with Version 2 :
-----------------------------------------------------------------------------
NAME
SPO_GetSampleList
SYNOPSIS
ULONG SPO_GetSampleList(APTR handle, struct SPO_SampleList **list)
D0 -$90 A1 A2
FUNCTION
While/after loading a Sample-File Version 2 SPObjects might create
a special list of all Samples, which appear in the File.
This will usually be one one Sample for SampleFiles, but many more
for ModuleFiles.
Not all SPObjects, especially not all ModuleType-SPObjects,
may support this and will return an error value or an empty list.
INPUT(S)
handle - a valid handle
list - a pointer to a SPO_SampleList pointer
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 2 of the superplay.library.
SEE ALSO
SPO_SetSampleList
-----------------------------------------------------------------------------
NAME
SPO_SetSampleList
SYNOPSIS
ULONG SPO_SetSampleList(APTR handle, struct SPO_SampleList *list)
D0 -$96 A1 A2
FUNCTION
For saving Sample-Files with Version 2 SPObjects, there may be used
a special list of all Samples, which should appear in the File.
This will usually be one one Sample for SampleFiles, but many more
for ModuleFiles.
Not all SPObjects, especially not all ModuleType-SPObjects,
may support this and will return SPERR_ACTION_NOT_SUPPORTED.
INPUT(S)
handle - a valid handle
list - a pointer to a SPO_SampleList
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 2 of the superplay.library.
SEE ALSO
SPO_GetSampleList
-----------------------------------------------------------------------------